BCI NET 2

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET 2 / BCI NET 2.iso / archives / utilities / time / pictureclock.lha / PictureClock / PictureClock.doc < prev next >

Wrap

Text File | 1994-08-22 | 23.0 KB | 491 lines

PictureClock V39.72 release 1.1 _________ . | . . / . . / . | / | |- ____/ -| | | . . . . . . ____|____ A broadcast clock for Amiga computers Works with Amiga OS V39 and up, also requires datatype.library V39 1 MB chip memory recommended for ECS graphics (up to 32 colours) 2 MB chip memory recommended for AA graphics (up to 256 colours) © Copyright 1994 by Maarten C. ter Mors All rights reserved. Legal issues page 1 -------------------------------------------------------------------------- Okay, let's get this out of the way first : the things you may and, mostly, the things you must and may _not_ do. This program, PictureClock, and its source code are copyrighted material. That means you may not make a profit out of it or out of part of it without the author's written permission. You are, however, allowed and even encouraged to distribute this program in any way you can, provided that you a) keep the distribution complete and distribute it in its original form and b) do not charge anybody money for it. If you intend to sell it or use it for any other commercial purpose that involves exchanging PictureClock for any other object of value, you must always first contact the author (see page 9). The inclusion of PictureClock in a public domain library is encouraged, just so long as no more than the equivalent of US$ 5 is charged for copying the disk, the disk itself and the shipping/handling. If you intend to include this program on a CD-ROM and the author did _not_ ask you to do so, he would be grateful for a copy of the CD-ROM in question. PictureClock was intended as a tool for people who work with television, video or multimedia presentations. Therefor you may use the clock freely on television, video tapes or during presentations, on screens in a conference hall, and so on. This goes for all sorts of productions, from filling the fifteen-second gap to the seven o' clock news, through motion pictures, to counting down the last seconds before midnight on Newyear's Eve. What you may NOT do is offer PictureClock as a service that you will be paid for, i.e. if you run a video production company and receive a call from a TV station, for example. You must then contact the author and he will try to work something out with you. As for the source code, it is mostly intended to learn from, as I have learned from other people's source code in the past. It is allowed to use parts of it in your own programs, as long as you : a) contact the author beforehand, so that he will be notified in advance and b) mention the author's name and the copyrights to his code along with your own copyright messages in the documentation to your program. See also : Notes on using the source code, page 6 About the author, page 9 Introduction page 2 -------------------------------------------------------------------------- We've all seen 'em, the clocks on TV that fill your entire screen and slowly tick away the seconds that separate you from the start of yet another episode of Dallas. Some of you may have thought they were great, fab examples of video artwork, others may have tapped their fingers on the table, desperately wanting them to go away. Some nutcase computer programmers may even have thought : 'I could do better than that.' Yep, you guessed it, I was one of those. I started programming this clock for no particular reason, other than that my summer holidays were well underway, which gave me a lot of time to spare, and that I wanted to experiment a bit with the new OS 3 datatypes a bit. So, PictureClock effectively was born as a small program called 'datatypetest.c', which was no more than a datatype-dependent picture viewer, and not a very good one at that. However, then I started to incorporate some older ideas that I had lying around in this head of mine. Coincedentally, I had recently been helping someone programming a small titlebar clock utility, so the idea of a clock came to mind. I had always wanted to do something with sound on the Amiga, so I added a subtask that chimes joyfully every whole and half hour, also through the (fabulous, albeit slow) datatype interface. In all, I renamed datatypetest.c to PictureClock.c and things really started to roll along. Well, what is it then ? After having let you read all the crap above, I think I'm obliged to tell you now. PictureClock is a full-screen analog clock utility, that draws a clock on top of a bitmap picture, that can be in any format, just as long as you have a pictureclass datatype to support it. Currently I know of picture ones for ILBM, GIF, JPEG, BMP, MacPaint, Sun Rasterfiles, Paintbrush (PCX) and I am still looking for one for PhotoCD - if anyone knows of a PhotoCD.datatype, please let me know ! Else I might consider writing one myself. PictureClock will automatically adapt to your overscan size, center pictures any size on-screen (if they are too large for the display, it will take whatever it can of the top lefthand corner). Theoretically, it will adapt itself to any size you care to throw at it, although very small pictures are not very useful ; the whole point of the program, is a clear, easy-to-read clock that you can see from a long way away if you have to. And on a 64x64 brush it will just be too tiny for that. You can tell PictureClock which picture to use by means of a command line from the Shell, by using a Project icon with its default tool set to PictureClock from Workbench, by a ToolType option or even by shift-clicking. In all cases, you can supply the name of a picture file, or the name of a directory with pictures in it from which PictureClock chooses a picture at random. Also, you can use any datatype-supported sound sample (datatypes are availible for 8SVX, WAV and other formats) to use as a 'chime' sound, just like an ancient church bell. PictureClock even supports a delay in seconds between alternate chimes, because else large samples could overlap and that sounds silly. Besides, a solemn graveyard bell loses much of its eerie sound when it's rung too quickly. How to use PictureClock page 3 -------------------------------------------------------------------------- PictureClock takes a number of options. From the CLI, you type these on the command line, after the name of the program. Like : PictureClock DH2:Pictures/Background.IFF NOTICK CONTINUOUS If you start the program from Workbench, you can enter the options through the so-called ToolTypes. These appear when you click on the program icon once and select 'Information' from the Icon menu. Here are the options, then, in all their glory : PICTURE ======= Behind this you type the name of the picture file you want to use as a background for your clock. It is also possible to specify the name of a directory, in which PictureClock will search for picture files. Do make sure that the file(s) is/are not in HAM format, since this is not supported by PictureClock (on page 5 I'll tell you why not). SOUND ===== Behind this belongs the name of the sound sample to use for the semi-hourly 'chime' sound. Just as with PICTURE above, the format of the file has to be supported by the datatypes installed on your system. I have included one sound sample in the archive, Bell, which is the solemn church bell I mentioned earlier. Anybody have a cuckoo sample for me ? WAITBETWEENSAMPLES (=WAIT) ========================== This option takes a number value that indicates the number of seconds to wait between chimes. This only applies to the full hour of course. To make the Bell sound sound good, a WAITBETWEENSAMPLES value of 1 is recommended. NOSEC ===== This turns the (red) seconds arm of the clock off. NOTICK ====== By default, PictureClock generates an InputEvent every second, that pretends to tap the left shift key. I have done this for two reasons : 1) to keep the screenblanker away and prevent it from blanking out your clock in the middle of a live TV performance (doesn't look very professional and the owner of the TV station might not be overly pleased). 2) in conjunction with the commodity Yak, which was written by Martin W. Scott & Gaël Marziou, and its keyclick feature, this makes a nice ticking sound every second. Just like a clock, really. How to use PictureClock page 4 -------------------------------------------------------------------------- CONTINUOUS (=CONT) ================== By default, the minute arm of the clock jumps forward one minute when the seconds reach 0. Now of course I know this is not the way a real clock works (not an analog one, anyway), and so you can tell it to move continually around the clock dial. If you look very closely you can still see it nudge itself forward a bit each second, especially on a LoRes screen, where the pixels are larger. However, my antique clock downstairs (which is really _fully_ analog) does this too on close inspection (especially when I put it in LoRes mode :-). I personally don't like the CONTINUOUS option (if only for the spelling), because the minute arm literally seems to crawl along, as if it's never learned to stand still ! But then, you may love it and so I decided to leave the option in. Go ahead, say it, I'm a nice guy :-)) BESTMODEID ========== This option lets PictureClock override the ModeID supplied by the datatype, because some have a way of providing rather dodgy ModeIDs, which render your picture rather strangely. It will call the graphics.library function BestModeID() to sort out the optimal screen mode for your picture. Use this option if you think your pictures don't look the way you remember them (wrong resolution, wrong overscan, etc.). BESTMODEID can have an unwanted side-effect, though : it chooses the screen mode in such a way, that it will suit the dimensions of the screen most properly. That means that if you have a small picture of, say, 300 by 200 pixels or so, which was actually drawn in high resolution, it will appear on screen slightly streched. This is because BestModeID() will pick a Lores non-interlaced screen mode to fit the picture. SLIM ==== It has come to my attention, that some people thought the arms of the clock were too large. Therefor, I added the SLIM option, which provides the same arms, except that they suddenly seem to have lost half their weight :-) Now if only I could bottle this stuff...:-)) What's still wrong with it page 5 -------------------------------------------------------------------------- PictureClock has its flaws. Apart from the fact that it could do with some additional features (see page 7), there are some known problems with the program. I will start with the most trivial : - The abbreviation sucks. You (probably) don't want to say to your friend : 'Hey Mick, I just got me this great program called PictureClock, it's fab ! PictureClock can put a clock on my screen and I almost wet my pants in delight when PictureClock started to chime the bells. It's also got a doc with it, called PictureClock.doc and it's almost just as good as PictureClock itself !' Now even if you would want to blurt out a load of rubbish like that, you'd shorten that word 'PictureClock' every time to something like PC. And, while it really only means 'Personal Computer', we all know what is generally *really* meant when somebody says 'PC'. He or she is then referring to those large, square boxes with noisy ventilators in them, that require a SoundBlaster and SVGA card to run a simple program like PC..er..PictureClock. - The program icon isn't much better. Apart from the fact that it looks terrible, I might get sued by Electronic Arts for unauthorised use and abuse of their DeluxePaint picture icon. Any unemployed artists out there to make me a proper icon ? - PictureClock does not support HAM pictures. Believe me, I've tried, but it's really no use. Getting the picture on screen is no problem, but drawing a clock over the top of it is hopeless. All the fringing makes the picture look like my mother-in-law on a very bad day indeed and the calculations to fix it every second eat up far too much processor time to do anything else. - PictureClock hangs. It doesn't crash, but it just hangs there when you change the system time to an earlier value than before, while PictureClock is running. I know why it happens - the TimeRequest the program is waiting for is not replied to until the original time comes around and so it waits in vain for a long time. This is probably the reason why Phil Collins sang, in one of the songs of his Both Sides album : Sometimes, hits me in the morning, hits me at night, that I cannot turn back the years Notes on using the source code page 6 -------------------------------------------------------------------------- The file PictureClock.c, which should be in this archive (if not, you have been given an incomplete archive - contact me for a complete one !), contains the C source code to PictureClock. Now you too can see how I did it, marvel at the clever bits of, drool over the beautiful parts of but most of all laugh at the inevitable, stupid mistakes in my code. You will notice that the source is a bit of a mess ; for one thing, all the code resides in one module and the better part of that is taken up by only one routine, the quite huge main() part. There are two reasons for this, one is that I started to write PictureClock as a try-out for the datatype routines and more and more grew on as time went by. The second reason is, that most of PictureClock's operation is pretty linear anyway : first parse the arguments, open the resources, the picture file, the screen, the window, draw the clock layout and so on. Then, all the way at the end of main(), there is a very small loop that is the actual heart of the program ; this is where the clock is actually being run from. I'm sorry that the source is also poorly commented, although I assume many things will be quite obvious. I never do too many obscure things, and the one or two that are there are either commented on the spot after all, or else explained in the autodocs. I recommend that you get them - they're an invaluable source of information for a serious programmer. In fact, I don't think I could have written PictureClock (with all its V39 functions I'd never even seen before) without them. The reason I included the source code, is that you can make small adaptations to the code yourself (provided of course that you are a programmer) if something does not suit you or if you have found a bug you know how to fix. I'd like to know about the bugs. You are allowed to do so for your own use. What I'd rather have you didn't (in other words : DON'T !), is distributing the adapted/fixed version yourself. This could cause too large a number of different versions of PictureClock made public, which in turn causes confusion and frustration. Two users who both use PictureClock 1.1 should get the same program, not two different ones with the same version number stuck to them. If you have made a change that you think could be useful to other PictureClock users, send it to me and I'll make it availible with the next release. I will release a new version when either many changes have been made, or there is one particular change that is so urgent (a serious bug, for example) that a new version needs to be brought out straight away. Program history page 7 -------------------------------------------------------------------------- I started programming at V39.00. That was a really useless program, with more errors than features and larger debug- than code hunks. Seventy-two revisions, additions and bugfixes later, I think PictureClock is ready to face the music. It is still far from perfect, and offhand I can think of a dozen features I could add to make the program all the more pretty and useful. Here are some I could do : - ARexx support. Especially in a TV/video environment, it could be extermely useful if you could let the clock tick until a certain time point, and then turn it off from ScalaMM for example. - Alarm timer. Do something (ARexx script ?) when a certain time point has been reached. In the above example, PictureClock could turn itself off when the time has come to do so. NOTE : It _is_ possible to interrupt PictureClock from an external program, for example an ARexx script. If you send it a CTRL-C break during execution, it will abort immediately. And since there are plenty of programs for the Amiga, that will let you execute at an exact time, you could circumvent above problems with a little bit of clever experimenting. - Screenblanker module. PictureClock is ideally suited to be a module for (for example) SuperDark, popping up after a period of inactivity from the user. There are only two problems with this : 1) the bars on the clock that indicate 12, 3, 6 and 9 o' clock will still burn in on your screen and 2) so will the picture. Problem 2 could be solved by adding : - Picture alternation. PictureClock could be told to change pictures every now and then, from a directory with picture files. This would, however, require a lot of chip memory. And PictureClock already takes up quite a lot of that because of its double buffering, so that may become a problem. - Text support. Scroll a line of text in a user-defined font across the bottom of the screen, and then preferably at a certain time or through external input (see above). For example : 'Next on BBC 2 : Monty Python's Flying Circus at 21:00'. - Weird features. Little men rubbing dirt off the arms of the clock, birds flying over the screen, a hollow laugh and some thunder at midnight, an irritating voice that tells you it's time to get up in the morning, and so on, and so on... If enough people write to me that they're interested in a certain feature, then I'll get it there. However, the source is included, so if you're worth your programming salt, make small changes yourself ! :-) Revision list page 8 -------------------------------------------------------------------------- PictureClock V39.58 (distributed as release 1.0b) ================================================= First release version. Includes source - and documentation with too many terrible jokes in it. PictureClock V39.72 (distributed as release 1.1) ================================================ * BUG fix : Apparently, the mouse pointer wasn't blanked in an entirely legal way, which could cause rubbish on the screen when moving the mouse. This has now been fixed by using the recommended, official and far too complicated method for V39. * BUG fix : Sometimes, the PictureClock sound sub-process would hang because of a problem with the stack. Fixed. * Improvement : Cleaned up the rather awkward manner in which the Workbench ToolTypes were organised. You no longer have to specify nonsense like 'NOTICK=TRUE', you can now just type 'NOTICK', just like from the CLI. Consequently, there is no longer any need for the TICK and SEC options and they are no longer supported. * Improvement : Fixed some problems with the aspect ratio of the clock on strangely-sized pictures. I used to calculate the pixel aspect ratio from the dimensions of the screen, now I go for the dimensions of the picture instead (usually, there isn't much difference, unless the picture is much smaller than the screen). * Improvement : The size of the four clock bars is now fully dependent on the size of the picture. * NEW feature : Added the SLIM option for slimmer clock arms. * NEW feature : Added the BESTMODEID option to fix problems with dodgy datatypes and wrong overscan settings. About the author page 9 -------------------------------------------------------------------------- If you should have any suggestions, bug reports, if you have made any changes to the source code of which you think it's worth it that they make it into the next version of PictureClock, or if you just desperately want someone to talk to (pretty women, this way please :-), then you can reach me at : Maarten ter Mors Hendrik Vinkhof 47 2202 XJ Noordwijk The Netherlands email : maarten.ter.mors@aobh.xs4all.nl Fido : 2:280/464.6 I'm ready for fanmail, hatemail, crazy mail, mail in yellow envelopes, mail that tastes good with pepper, mail in green envelopes, mailbombs, mail in any other colour envelope, no mail at all and even SERIOUS mail. I do, however, prefer email whenever possible, it's so much easier (too bad about the coloured envelopes, though. Damn ! :-) What I'm not ready for, on the other hand, is a great deal of money, Amigas 4000, shiny sportscars and houses by the sea. So whatever you do, DON'T send them ! (Now let's see if it's true what they say, that people always do what you don't want them to :-) Oh, and I don't expect the Spanish Inquisition either. 'NOBODY EXPECTS...' THE END '....o bugger.' By the wee : my PeeGeePee key page 10 -------------------------------------------------------------------------- O yeah, by the way. If you don't want your husbands to know, ladies, that's quite allright. Here's my PGP public key for your convenience : -----BEGIN PGP PUBLIC KEY BLOCK----- Version: 2.3a.2 mQCNAizFdygAAAEEAMUcoE5jO7xw13BVEdMwMuzc513YU55N0pOECQZvxpt+vJ0z WxDxuZ3bVgTR9YsP8ZkOZm4Eu8XCbqElenmnMMbBwKHScrF5SB/tpgHw/Xh8DHNm NgBvPnvNOW7x3DLZ27L+dvuuafJJ2RdA3NLLAoNAQX9sbS/ZNwLexz+VJ8G3AAUR tCFNYWFydGVuIEMuIHRlciBNb3JzIDwyOjI4MC80NjQuNj6JAJYCBRAsxq0kSnwH D6aK11kBAT4XBAIC0jZSswryiB6rcrb7Tj0DQGOvaZjFwQl6IJqIDsPUrLCH/tPY NnfzMCYcqe3ul72BW1hdPhE7YWjOaX2my0o54HH3J8R8y1CBcV521mTolcA+1/Rn drmiyt5eaRoXcE6rb0Nj4OEkHyluNLkvm6D8ZwTlVWIACdIanzTCCNhzMGG0EE1h YXJ0ZW4gdGVyIE1vcnM= =98JL -----END PGP PUBLIC KEY BLOCK-----